Developer CD Series 1994 November: Tool Chest/Dev.CD Nov 94.toast/Sample Code/AOCE Sample Code/Digital Signatures/Digital Signature Demo/Using Digital Signature Demo/Using Digital Signature Demo

Text File | 1994-06-23 | 58.3 KB | 73 lines | [ONLN/HLX2]

Digital Signature Demo
Martin Minow
Developer Technical Support
Introduction
The Digital Signature Demo illustrates how AOCE Digital Signature technology may be incorporated into an existing application with a minimum of fuss, and without significantly perturbation of the existing application.
The demo extends the Think Class Library “Tiny Edit” sample program, allowing documents created by TinyEdit to be “signed” and “verified” by the Digital Signature Manager. It also shows how Digital Signatures may be applied to application data, such as the state of checkboxes and radio buttons.
Although the class is defined for, and operates within the Think Class Library organizational structure, it should be relatively easy to adapt it to other class hierarchies. Even if you do not use a class library design in your own applications, you should still be able to use the demo as a basis for your own Digital Signature subroutine library.
Class Hierarchy
The demo defines a CSignature class and two subclasses that are used to manipulate digital signatures. It also adds a few simple classes that add the necessary capabilities to TinyEdit. The class hierarchy is as follows:
Class        Description
CSignature        The base class for Digital Signatures. CSignature is a subclass to the base-class, CObject. Applications normally do not create instances of this class, but rather use subclasses.
    CSignedDataFile    This class allows signing or verifying an entire file. It is used to sign a document after it has been saved to disk, and to verify an existing signed document.
    CSignedObject    This class allows signing or verifying a data object. Your application should create a subclass with the necessary content and methods. You can then use CSignedObject methods to sign or verify the object’s actual data.
Sample Program
The sample program is an extension of the Think Class Library “TinyEdit” sample application. It extends the CEditDoc class to provide for signed and verified text files and adds a sample class to show how you can sign and verify the contents of a dialog. The demo requires the following source files and their headers:
File    Description
DigitalSignatureDemo.c    This is the main program. It creates a DemoApp class.
DemoApp.c    This is a subclass to CEditApp that lets you open signed documents and starts the signed object demo. It also overrides a “shutdown” method to ensure that the signature context has been removed when your application exits.
DemoEditDoc.c    This is a subclass to CEditDoc that lets you sign and verify documents. It also has methods override CEditDoc methods in order to provide better error messages.
DemoSignedObject.c    This object can sign and verify its data contents. It is a subclass to CSignedObject.
DemoSignedObjectDialog.c    This dialog manages a DemoSignedObject instance. It displays a dialog that lets you change checkbox and text items, and controls signing, verifying, and other CSignedObject functions. It is a subclass to CDLOGDirector. Although it appears to the user as a modal dialog, it is actually implemented as a normal window.
ErrorMessage.c    This file contains two simple display functions for debugging convenience. Error messages were included within the program text so there was a single reference point that explains errors. A production program should preferably store its error messages in resource files
SIGStatusManager.c    This contains the status window manager, window, and window contents. This window is displayed when you specify the built-in status window for a Sign or Verify operation.
SystemSupportsAOCE.c    This subroutine tests for the presence of the AOCE toolbox. It returns an error if the toolbox was not installed or was disabled.
Potential Problems
There are a few things that application developers need to be aware of when using Digital Signatures (these are independent of the example):
•    When your application exits, be sure that you have disposed of the signing context (SIGContextPtr datum). In general, this means that your application should patch the ExitToShell trap with a small subroutine that checks for an active context. The sample program stores the context pointer in a global variable, and overrides CApplication::RemovePatches to check that it has been deleted when the application exits.
•    Signing and verifying take a fairly long time; your application should use a status procedure to entertain the user while signing. This entails a bit of effort: you should not initiate signing or verifying from a Modal Dialog, but should use some form of “standard” window or a non-modal dialog. In the example, the signed object demo uses a subclass of TCL’s CDialog class, which implements a modal-dialog lookalike using the normal window-based event loop. The reason for this is that your status callback should call your normal event loop: if you have an active modal dialog, it will not receive update events properly.
•    When a file is signed, it is set “locked,” i.e., read-only This means that your application must open it read-only (fsRdPerm). Also, your users cannot create a new file with the same name without first, manually, renaming the file or placing it into the trash.
•    The method descriptions only describe the errors that your application needs to handle (because they’re benign or expected). However, note that there are a number of other Digital Signature Manager errors that may also occur. You should carefully test your application to make sure it displays informative error messages in all circumstances.
    There are a number of instances where errors should be detected in your application. For example, signed files are read-only (“locked”) and must be opened with permission set to fsRdPerm, rather than the standard fsRdWrPerm. You should search the demo for Message() calls to see those errors I found worth detecting.
The remainder of this document describes the individual classes.
CSignature
Introduction
CSignature is the base class for Digital Signature processing. It contains methods that all Digital Signature processing requires, as well as a few utility classes. Your application does not use CSignature directly, but rather uses one of its sub-classes.
Heritage
Superclass    CObject
Subclasses    CSignedDataFile, CSignedObject
Global Variables
Variable    Type    Description
gSIGStatusProc    SIGStatusProcPtr    Default status procedure: pass this to Sign, SignFile, etc. to use the built-in procedure.
gSIGContextPtr    SIGContextPtr    The Signer Manager context. Be sure that your application disposes of any context before it terminates.
Global Functions
void                DisposeSignerContext(void);
Dispose of the signer context, if it exists. This must be called when your application exits (you should trap ExitToShell so you call DisposeSignerContext even if your application crashes).
Instance Variables
Variable    Type    Description
itsContextType    unsigned long    This is the type of the context variable: it is needed only by methods that enable/disable the ShowSigner option as that option is valid only after verifying an object or file.
itsStatusManager    SIGStatusManager    An instance of this class is created if you specify the default status window.
Methods
Construction and destruction methods
void                ISignature(void);
Initialize the private variables.
void                Dispose(void);
Delete any context and signature and dispose of the CSignature object.
Signer Context Methods
void            NewContext(
    unsigned long        contextType
);
Create a new context of the indicated type. The contextType parameter may be one of the following values, which are defined in <DigitalSignature.h>
kSIGSign    Signing a file or object
kSIGVerify    Verifying a file or object
kSIGDigest    Preparing a digest of an object
void                CheckForContext(void);
Fail if there is no current context with a kSIGContextPrepareErr. This would indicate a programming error where one of the routines that requires a context was called when there was no context. For example, calling Sign when your application hasn’t called SignPrepare, would cause this failure.
unsigned long        GetContextType(void);
Return zero if there is no current context, else the type that was specified when the application called NewSignerContext.
Signature Methods
Size                SignPrepare(
    const FSSpec        *signerFile,
    ConstStr255Param    *prompt
);
SignPrepare prepares the Signer Manager to sign a document or data. If signerFile is not NULL, it will be used to define the signer file, while if NULL, the toolbox will prompt for the user’s signer file. Prompt is used to prompt the user for a signer file, if "\p", the default prompt will be used. SignPrepare returns the size of the Signature record.
SignPrepare our application should  use a TRY/CATCH context to detect the following errors:
kSigUserCanceled    The user cancelled this signer request. You may choose to ignore this error.
kSIGPasswordErr    The user did not enter the proper password for the designated signer file.
kSIGSignerNotValid    The signer file is not valid; perhaps it has expired.

void                ShowSigner(void);
After your application has successfully verified a file or object, ShowSigner may be used to display the entire distinguished name of the object’s or file’s signer. Your TRY/CATCH context should catch the following error:
kSIGOperationIncompatibleErr    ShowSigner is valid only after verification; it cannot be used after signing an object or file. See the signed object demo for an example of how a button that controls this request may be enabled or disabled as needed.

void                GetSignerInfo(
    SIGSignerInfo        *signerInfo
);
After successfully signing or verifying an object or file, you can call this method to copy information about the signer to your buffer. The buffer should be in locked memory.
Boolean            GetCertInfo(
    unsigned long        certIndex,
    SIGCertInfo        *certInfo
);
GetCertInfo can be used to iterate through the certificates that make up a signature. It returns TRUE if it finds a certificate for this index, FALSE if the index is out of range, and fails on other errors. It may be called only after successfully signing or verifying an object or file.
Boolean            GetCertNameAttributes(
    unsigned long        certIndex,
    unsigned long        attributeIndex,
    SIGNameAttributesInfo *attributeInfo
);
GetCertInfo can be used to iterate through the attributes for a certificate. It returns TRUE if successful, FALSE if the certIndex is out of range, and raises an error condition on other errors. It may be called only after successfully signing or verifying an object or file.
Protected Methods
void                InitDefaultStatusProc(
    ConstStr255Param    actionString,
    ConstStr255Param    objectString
);
This is called if you pass gSIGStatusProc to SignFile, VerifyFile, etc. It creates a SIGStatusManager object which displays the status window.
void                DisposeDefaultStatusProc(void)
Dispose of the status window.
SIGStatusManager
Introduction
SIGStatusManager manages the status window that is displayed when an application selects the default status procedure. It is created and managed by the CSignature instance: your application will normally not be concerned with it.
Heritage
Superclass    CDirector
Subclasses    none
Instance Variables
Variable    Type    Description
itsTickCount    unsigned long    This is used to time the “barber pole” progress indicator.
Static Variables
Variable    Type    Description
gContinueSigning Boolean    This is set TRUE when signing begins, and is set FALSE if the user clicks on the Cancel button. The value is passed to the Digital Signature Manager by the default status procedure.
Methods
Construction and destruction methods
void                ISIGStatusManager(
    ConstStr255Param    actionString,
    ConstStr255Param    objectString
);
Create the status window (this uses some private classes that are defined in SIGStatusManager.c). The actionString and objectString are concatenated and displayed in the window. These might typically be “Signing “ “Signed File.”
Operational methods
void                DoCommand(
    long                aCommand
);
The status window has a cancel button: look for it and take appropriate action by setting gContinueSigning FALSE and passing the cancel command to the manager’s superclass.
void                Dawdle(
    long                *maxSleep
);
TCL calls this repeatedly to manage the progress indicator.
CSignedObject
Introduction
CSignedObject lets you sign and verify the contents of an individual data object, such as a spreadsheet value or the position of an object in a drawing application. You can then store and recover the signature record as part of your application’s normal storage process.
Heritage
Superclass    CSignature
Subclasses    none
Instance Variables
Variable    Type    Description
itsSignature    SIGSignaturePtr    The signature record, if any.
itsSignatureSize    Size    The size of the signature record.
Using CSignedObject
Your application should create a subclass of CSignedObject for all objects that need data-specific signature processing.
Methods
Except as shown, all methods use the Failure mechanism (as described in <Exceptions.h> to report errors. In most cases, this means that your application must establish a TRY/CATCH context when calling these methods:
kSIGUserCanceled    The user cancelled this sign or verify request. You may choose to ignore this error.
kSIGPasswordErr    The user entered an incorrect password.
kSIGSignerNotValidErr    The signer file is not valid; perhaps it has expired.
kSIGNoSignature    Programming error: your application called Sign or Verify without having called SignPrepare or VerifyPrepare.
kSIGVerifyFailedErr    Verification failed.
kSIGInvalidCredentialErr    Verification succeeded, but credentials are invalid; perhaps they have expired.
kSigSignerErr    Some sort of error with the signer: the signature is not valid.
 Construction and destruction methods
void                ISignedObject(void);
Initialize the private variables.
void                Dispose(void);
Delete any context and signature and dispose of the CSignature object.
Signing and Verifying Methods
Size                SignPrepare(
    const FSSpec        *signerFile,
    ConstStr255Param    *prompt
);
Override CSignature::SignPrepare to store the signature size.
void                Sign(
    SIGStatusProcPtr    statusProc
);
Sign completes the digital signature process. To sign an object, you should call SignPrepare, ProcessData, and then Sign. The statusProc, if not NULL, may be used to inform the user that a signature operation is occurring.  Errors are reported using the Failure mechanism.
void                VerifyPrepare(
    SIGStatusProcPtr    statusProc
);
Begin the process of verifying a digital signature process. To verify an object, you should call VerifyPrepare, ProcessData, then Verify. Errors are reported using the Failure mechanism.
void                Verify(void);
Verify completes the digital signature verification. Errors are reported using the Failure mechanism.
void                ProcessData(
    const void        *dataPtr,
    Size                dataSize
);
Compute or verify a Digital Signature. This is called for all data elements.
Signature Methods
Size                GetSignatureSize(void);
Return the size of the signature record, as specified—originally—by SignPrepare.
void                NewSignature(void);
Create a signature record using the currently-specified size.
void                DisposeSignature(void);
Dispose of the current signature buffer, if any, but do not dispose of the context.
Boolean            HasSignature(void);
Return TRUE if there is a current signature.
void                CheckForSignature(void);
Fail with an error (kSIGNoSignature) if the application hasn’t established a signature record.
void                CopySignatureToUserBuffer(
    void                *buffer,
    Size                bufferSize
);
Copy the current signature to the user’s buffer. BufferSize is the size of the user’s buffer; a paramErr error condition will be raised if bufferSize cannot hold the entire signature.
void                MakeSignatureFromUserBuffer(
    void                *buffer,
    Size                bufferSize
);
Create a signature record using the information in the user’s buffer. CopySignatureToUserBuffer and MakeSignatureFromUserBuffer may be used together to save and restore object signatures.
void                ReadSignature(
    CDataFile            *aFile
);
Read a signature record from the indicated file. If a non-null signature was read, create it from the given data. The actual data includes a header record that indicates that the data is a signature and specifies its length.
void                WriteSignature(
    CDataFile            *aFile
);
Write a signature to an open file. This might be called as part of your “save this object” process. aFile is a TCL data file. This also writes a header record with the signature length: if it is called when there no signature record, it will write a zero-length record that ReadSignature correctly interprets.
CSignedDataFile
Introduction
CSignedDataFile lets you sign and verify the contents of an entire file.
Heritage
Superclass    CSignature
Subclasses    none
Using CSignedDataFile
Use this as part of your application’s Open and Close document processing.
Methods
Except as shown, all methods use the Failure mechanism (as described in <Exceptions.h> to report errors. In certain cases, this means that your application must establish a TRY/CATCH context when calling these methods.
Construction and destruction methods
void                ISignedDataFile(void);
Initalize the object instance.
void                SignFile(
    const FSSpec        *signerFile,
    ConstStr255Param    promptString,
    const FSSpec        *dataFile,
    SIGStatusProcPtr    statusProc
);
Sign the file specified by dataFile. If signerFile is not NULL, it will be used to define the signer file, while if NULL, the toolbox will prompt for the user’s signer file. Prompt is used to prompt the user for a signer file, if "\p", the default prompt will be used. SignPrepare returns the size of the Signature record. StatusProc defines the user status procedure. Use gSIGStatusProc for the default window.
Because of the way the Think Class Library closes files, you should call SignFile in the following sequence:
1    Create a copy of the FSSpec associated with the file.
2    Write all data and close the file. You can delete the CDataFile object at this time.
3    SignFile using the saved FSSpec.
4    Call DisposeSignerContext
You should call SignPrepare…SignFile in a TRY/CATCH context, checking for the following errors:
kSIGUserCanceled    The user cancelled this signer request. You may choose to ignore this error.
kSIGPasswordErr    The user entered an incorrect password.
kSIGSignerNotValid    The signer file is incorrect.
wrPermErr    The data file is marked read-only (perhaps it was already signed?)
void                VerifyFile(
    const FSSpec        *dataFile,
    SIGStatusProcPtr    statusProc
);
Verify the signature in the file specified by dataFile.  StatusProc defines the user status procedure. Use gSIGStatusProc for the default window. You should call VerifyFile in a TRY/CATCH context, checking for the following errors:
kSIGUserCanceled    The user cancelled this verification request. You may choose to ignore this error.
kSIGVerifyFailedErr    Verification failed: the file or signature may have been changed.
kSIGInvalidCredentialErr    Verification succeeded, but the credentials are pending or have expired. The context is still active.
Boolean            FileIsSigned(
    const FSSpec        *dataFile,
);
Return TRUE if the specified file has a signature. Note that the signature is not verified.
æ◊#ˇˇˇˇˇ#◊

d,Palatino
.+Z.Digital Signature Demo(.

1)
.

°dONLNd5\N
À(fzDIGITAL SIGNATURE DEMO,    Helvetica
°dONLNdNÿ]
O+|MARTIN MINOW°dONLNd$\êk
ó(ÜÆDEVELOPER TECHNICAL SUPPORT°dONLNd@É<íì(≠ZIntroduction
°dONLNdMù<´
¥*AThe Digital Signature Demo illustrates how AOCE Digital Signature°dONLNdè´<π
Ï*Jtechnology may be incorporated into an existing application with a minimum°dONLNd⁄π<«
–*Lof fuss, and without significantly perturbation of the existing application.°dONLNd
'Õ<€
…*DThe demo extends the Think Class Library “Tiny Edit” sample program,°dONLNd
l€<È
·*Kallowing documents created by TinyEdit to be “signed” and “verified” by the°dONLNd
∏È<˜
«*FDigital Signature Manager. It also shows how Digital Signatures may be°dONLNd
ˇ˜<

„*Oapplied to application data, such as the state of checkboxes and radio buttons.°dONLNdO
<

È*NAlthough the class is defined for, and operates within the Think Class Library°dONLNdû
<
'
‡*Qorganizational structure, it should be relatively easy to adapt it to other class°dONLNd
'<
5
∏*Fhierarchies. Even if you do not use a class library design in your own°dONLNd7
5<
C
‡*Napplications, you should still be able to use the demo as a basis for your own°dONLNdÜ
C<
Q
*%Digital Signature subroutine library.

°dONLNd¨
]<
lÆ*Class Hierarchy
°dONLNdº
w<
Ö
»*GThe demo defines a CSignature class and two subclasses that are used to°dONLNd
Ö<
ì
◊*Mmanipulate digital signatures. It also adds a few simple classes that add the°dONLNdR
ì<
°
™*Fnecessary capabilities to TinyEdit. The class hierarchy is as follows:°dONLNdô
¢<
∞X*Class°dONLNd†
¢‰
∞
$)®Description"
¿U#"
¿Vv"
¿Õ"
¿Œ."
¿˝ 
¿˛
¿("
¿)#"
¡U
"
¡˝
"
¡)
,
Courier°dONLNd≠
π<
ł(
‚Z
CSignature°dONLNdπ
∑‰
≈(
‡
6The base class for Digital Signatures. CSignature is a°dONLNd
≈‰
”
Á*1subclass to the base-class, CObject. Applications°dONLNd"
”‰
·
Ú*3normally do not create instances of this class, but°dONLNdV
·‰
Ô
Y*rather use subclasses."
œU"
œVv"
œÕ"
œŒ."
œ˝ 
œ˛
œ("
œ)"
–U="
–˝="
–)=°dONLNdo
¯TΩ(!rCSignedDataFile°dONLNd
ˆ‰
˛(
6This class allows signing or verifying an entire file.°dONLNd∂‰
ˇ*5It is used to sign a document after it has been saved°dONLNdω 
˚*3to disk, and to verify an existing signed document."U"V"m"n^"Õ"Œ."˝ ˛(")"U/"˝/")/°dONLNd")T5Ø(Rr
CSignedObject°dONLNd0'‰5
˙(P
5This class allows signing or verifying a data object.°dONLNdf5‰C
¯*2Your application should create a subclass with the°dONLNdôC‰Q
˜*/necessary content and methods. You can then use°dONLNd…Q‰_*4CSignedObject methods to sign or verify the object’s°dONLNd˛_‰m
"*actual data."?U"?V"?m ?n?¸"?˝ ?˛?("?)"@UK"åU"åm ånå¸"@˝K"å˝ å˛å("@)K"å)

°dONLNdz<â¥(§ZSample Program
°dONLNdî<¢
◊*HThe sample program is an extension of the Think Class Library “TinyEdit”°dONLNdd¢<∞
÷*Ksample application. It extends the CEditDoc class to provide for signed and

*&:Copyright © 1993, Apple Computer Inc. All Rights Reserved.(Ò??ˇ
ƒ◊#ˇˇˇˇˇ#◊

d,Palatino
.+Z.Digital Signature Demo(.

2)
.°dONLNd)<7
Ï(RZOverified text files and adds a sample class to show how you can sign and verify°dONLNdP7<E
“*Jthe contents of a dialog. The demo requires the following source files and°dONLNdõE<Sà*their headers:
°dONLNd™STai+File°dONLNdØSa
0)úDescription°dONLNdªaToŸ(ärDigitalSignatureDemo.c°dONLNd“ao
Ω)ú&This is the main program. It creates a°dONLNd˘o}
I*DemoApp class.°dONLNd
}Tãñ(¶r    DemoApp.c°dONLNd
}ã
€)ú,This is a subclass to CEditApp that lets you°dONLNd
?ãô
Ë*+open signed documents and starts the signed°dONLNd
kôß
„*+object demo. It also overrides a “shutdown”°dONLNd
óßµ
„*+method to ensure that the signature context°dONLNd
√µ√
◊*&has been removed when your application°dONLNd
Í√—
*exits.°dONLNd
Ò—Tfl©(˙r
DemoEditDoc.c°dONLNd
ˇ—fl
ÿ)ú,This is a subclass to CEditDoc that lets you°dONLNd,flÌ
¡*&sign and verify documents. It also has°dONLNdSÌ˚
Õ*$methods override CEditDoc methods in°dONLNdx˚
    
≈*'order to provide better error messages.°dONLNd†
    T
Δ(
2rDemoSignedObject.c°dONLNd≥
    

¬)ú(This object can sign and verify its data°dONLNd‹

%
’*,contents. It is a subclass to CSignedObject.°dONLNd    
%T
3Í(
NrDemoSignedObjectDialog.c°dONLNd"
%
3
ÿ)ú&This dialog manages a DemoSignedObject°dONLNdI
3
A
–*,instance. It displays a dialog that lets you°dONLNdv
A
O
Ë*,change checkbox and text items, and controls°dONLNd£
O
]
·*+signing, verifying, and other CSignedObject°dONLNdœ
]
k
‚*-functions. It is a subclass to CDLOGDirector.°dONLNd˝
k
y
€**Although it appears to the user as a modal°dONLNd(
y
á
¿*'dialog, it is actually implemented as a°dONLNdP
á
ï
N*normal window.°dONLNd_
ïT
£ß(
ærErrorMessage.c°dONLNdn
ï
£
ª)ú%This file contains two simple display°dONLNdî
£
±
·**functions for debugging convenience. Error°dONLNdø
±
ø
Ê*)messages were included within the program°dONLNdÈ
ø
Õ
Ë*/text so there was a single reference point that°dONLNd
Õ
€
Δ*%explains errors. A production program°dONLNd?
€
È
„*-should preferably store its error messages in°dONLNdm
È
˜
9*resource files°dONLNd|
˜T√( rSIGStatusManager.c°dONLNdè
˜
€)ú(This contains the status window manager,°dONLNd∏
Ï*(window, and window contents. This window°dONLNd·!
’**is displayed when you specify the built-in°dONLNd!/
Í*-status window for a Sign or Verify operation.°dONLNd:/T=ÿ(XrSystemSupportsAOCE.c°dONLNdO/=
‚)ú-This subroutine tests for the presence of the°dONLNd}=K
»*(AOCE toolbox. It returns an error if the°dONLNd¶KY
‘**toolbox was not installed or was disabled.,    Helvetica

°dONLNd—e<tƒ(èZPotential Problems
°dONLNd‰<ç
·*KThere are a few things that application developers need to be aware of when°dONLNd0ç<õ
ü*@using Digital Signatures (these are independent of the example):

*;:Copyright © 1993, Apple Computer Inc. All Rights Reserved.(Ò??ˇΔ◊#ˇˇˇˇˇ#◊

d,Palatino
.+Z.Digital Signature Demo(.

3)
.°dONLNd3`Ag(\~
•
°dONLNd3mA
%)
 When your application exits, be °dONLNd"3
%A
»)∏sure that you have disposed
°dONLNd>AmO
Ç(jã1of the signing context (SIGContextPtr datum). In °dONLNdoA
ÇO
»(j
†
general, this°dONLNd}Om]
W(xã)means that your application should patch 
°dONLNd¶O
W]
»)Íthe ExitToShell trap°dONLNdª]mkµ(Üã
with a small 
°dONLNd»]µk
»)H1subroutine that checks for an active context. The°dONLNd˙kmy
i(îã-sample program stores the context pointer in 
°dONLNd
'k
iy
»)¸a global variable,°dONLNd
:ymá
(¢ã-and overrides CApplication::RemovePatches to °dONLNd
gy
á
»(¢
ù
check that it°dONLNd
uámï
`(∞ã,has been deleted when the application exits.°dONLNd
¢ü`≠g(»~
•°dONLNd
§üm≠
)
Signing and verifying take 
°dONLNd
øü
≠
»)ñ$a fairly long time; your application°dONLNd
‰≠mªÂ(÷ãshould use a status °dONLNd
¯≠ª
»)x%procedure to entertain the user while°dONLNdªm…º(‰ãsigning. This °dONLNd,ªº…
»)O0entails a bit of effort: you should not initiate°dONLNd]…m◊
(Úãsigning or verifying from a °dONLNdy…
◊
»)®Modal Dialog, but should use
°dONLNdñ◊mÂæ(
ã
some form of °dONLNd£◊æÂ
»)Q+“standard” window or a non-modal dialog. In
°dONLNdœÂmÛ
(
ãthe example, the signed object °dONLNdÓÂ
Û
»)Ædemo uses a subclass of TCL’s°dONLNdÛm

¡(
ãCDialog class, °dONLNdÛ¡


»)T)which implements a modal-dialog lookalike°dONLNdE

m

ç(
*ã.using the normal window-based event loop. The °dONLNds


ç

»(
*
´
reason for°dONLNd~
m
«(
8ãthis is that your 
°dONLNdê
«

»)Z-status callback should call your normal event°dONLNdæ
m
+ô(
Fã    loop: if °dONLNd«
ô
+
»),4you have an active modal dialog, it will not receive°dONLNd¸
+m
9(
Tãupdate events properly.°dONLNd
C`
Qg(
l~
•°dONLNd
Cm
Q

)
When a file is signed, it is °dONLNd3
C


Q
»)†"set “locked,” i.e., read-only This°dONLNdV
Qm
_æ(
zãmeans that     °dONLNda
Qæ
_
»)Q'your application must open it read-only°dONLNdâ
_m
m
8(
àã$(fsRdPerm). Also, your users cannot 
°dONLNd≠
_
8
m
»)Àcreate a new file with the°dONLNd»
mm
{
º(
ñã5same name without first, manually, renaming the file °dONLNd˝
m
º
{
»(
ñ
⁄or°dONLNd
{m
âÒ(
§ãplacing it into the trash.°dONLNd
ì`
°g(
º~
•°dONLNd
ìm
°π)
The method °dONLNd(
ìπ
°
»)L/descriptions only describe the errors that your°dONLNdX
°m
Ø¥(
 ãapplication °dONLNdd
°¥
Ø
»)G*needs to handle (because they’re benign or°dONLNdè
Øm
Ω®(
ÿãexpected). °dONLNdö
Ø®
Ω
»);.However, note that there are a number of other°dONLNd…
Ωm
À
l(
Êã*Digital Signature Manager errors that may °dONLNdÛ
Ω
l
À
»)ˇalso occur. You°dONLNd
Àm
Ÿó(
Ùãshould 
°dONLNd

Àó
Ÿ
»)*8carefully test your application to make sure it displays°dONLNdC
Ÿm
Á
z(ã0informative error messages in all circumstances.°dONLNdu
Òm
ˇ
d*&There are a number of instances where °dONLNdõ
Ò
d
ˇ
»)˜errors should be°dONLNd¨
ˇm
≤((ãdetected in °dONLNd∏
ˇ≤

»)E/your application. For example, signed files are°dONLNdË
m•(6ã
read-only 
°dONLNdÚ
•
»)81(“locked”) and must be opened with permission set°dONLNd$m)

(Dãto fsRdPerm, rather than °dONLNd=

)
»)ùthe standard fsRdWrPerm. You°dONLNdZ)m7
ü(Rã8should search the demo for Message() calls to see those 
°dONLNdí)
ü7
»(R
Ωerrors I°dONLNdõ7mEÏ(`ãfound worth detecting.°dONLNd≥K<Y
§(tZ@The remainder of this document describes the individual classes.

*}:Copyright © 1993, Apple Computer Inc. All Rights Reserved.(Ò??ˇ¿◊#ˇˇˇˇˇ#◊

d,Palatino
.+Z.Digital Signature Demo(.

4)
.,    Helvetica
°dONLNd5<Dç(_Z
CSignature
°dONLNdI<Xì*Introduction
°dONLNd]<k
¬*JCSignature is the base class for Digital Signature processing. It contains°dONLNdck<y
‰*Pmethods that all Digital Signature processing requires, as well as a few utility°dONLNd¥y<á
Ë*Oclasses. Your application does not use CSignature directly, but rather uses one°dONLNd
á<ïò*of its sub-classes.

°dONLNd
õ<™z*Heritage
°dONLNd
!©T∑é+
Superclass°dONLNd
,©∫∑‰)fCObject°dONLNd
4∑T≈ç(‡r
Subclasses°dONLNd
?∑∫≈
l)fCSignedDataFile, CSignedObject

°dONLNd
^À<⁄≥(ıZGlobal Variables
°dONLNd
oŸTÁÉ+
Variable°dONLNd
xŸ∫Á’)fType°dONLNd
}Ÿ
8Á
x)~Description°dONLNd
âÁTı®(
rgSIGStatusProc°dONLNd
òÁ∫ı
)fSIGStatusProcPtr°dONLNd
©Á
8ı
‹)~Default status procedure: pass°dONLNd
»ı
8

Á*#this to Sign, SignFile, etc. to use°dONLNd
Ï

8

µ*the built-in procedure.°dONLNd
T
©(
:rgSIGContextPtr°dONLNd
∫

    )f
SIGContextPtr°dONLNd!

8

Ë)~The Signer Manager context. Be°dONLNd@

8
-
«*sure that your application°dONLNd[
-
8
;
Ê*!disposes of any context before it°dONLNd}
;
8
I
w*terminates.

°dONLNdâ
O<
^∂(
yZGlobal Functions,
Courier
°dONLNdö
cT
op+void°dONLNd¢
cÃ
o
â)xDisposeSignerContext(void);°dONLNdæ
u<
É
≈(
ûZJDispose of the signer context, if it exists. This must be called when your°dONLNd    
É<
ë
v*:application exits (you should trap ExitToShell so you call°dONLNdD
ë<
ü
p*7DisposeSignerContext even if your application crashes).

°dONLNd|
•<
¥¬*Instance Variables
°dONLNdè
≥T
¡É+
Variable°dONLNdò
≥∫
¡’)fType°dONLNdù
≥
8
¡
x)~Description°dONLNd©
¡T
ϧ(
ÍritsContextType°dONLNd∏
¡∫
œ

)f
unsigned long°dONLNdΔ
¡
8
œ
⁄)~This is the type of the context°dONLNdÊ
œ
8
›
’*variable: it is needed only by°dONLNd
›
8
Î
Í*methods that enable/disable the°dONLNd%
Î
8
˘
À*ShowSigner option as that°dONLNd?
˘
8
¡*option is valid only after°dONLNdZ
8
Δ*verifying an object or file.°dONLNdwT#¥(>ritsStatusManager°dONLNdà∫#
!)fSIGStatusManager°dONLNdô
8#
…)~An instance of this class is°dONLNd∂#
81
È*"created if you specify the default°dONLNdŸ1
8?
å*status window.

°dONLNdËE<Tz(oZMethods
°dONLNdY<g
*$Construction and destruction methods°dONLNdmTyp+void°dONLNdmÃy
C)xISignature(void);°dONLNd/<çÊ(®Z!Initialize the private variables.°dONLNdQìTüp+void°dONLNdYìÃü
.)xDispose(void);

(ÒZ:Copyright © 1993, Apple Computer Inc. All Rights Reserved.(Ò??ˇ
n◊#ˇˇˇˇˇ#◊

d,Palatino
.+Z.Digital Signature Demo(.

5)
.°dONLNd/<=
æ(XZFDelete any context and signature and dispose of the CSignature object.
°dONLNdGC<Q¬*Signer Context Methods,
Courier°dONLNd^WTcp+void°dONLNdeW¥c

)`NewContext(°dONLNdrclo«(åä
unsigned long°dONLNdÅc‰o
1)xcontextType°dONLNdçoT{b(òr);°dONLNdêÅ<è
È(™ZLCreate a new context of the indicated type. The contextType parameter may be°dONLNd›è<ù
Δ*Fone of the following values, which are defined in <DigitalSignature.h>°dONLNd
$ùN´Ç+kSIGSign°dONLNd
-ù∫´
5)lSigning a file or object°dONLNd
F´Nπå(‘l
kSIGVerify°dONLNd
Q´∫π
?)lVerifying a file or object°dONLNd
lπN«ã(‚l
kSIGDigest°dONLNd
wπ∫«
^)lPreparing a digest of an object°dONLNd
óÕTŸp(ˆrvoid°dONLNd
üÕß
f)xCheckForContext(void);°dONLNd
∂fl<Ì
·(
ZLFail if there is no current context with a kSIGContextPrepareErr. This would°dONLNdÌ<˚
Δ*Findicate a programming error where one of the routines that requires a°dONLNdJ˚<
    
Ï*Lcontext was called when there was no context. For example, calling Sign when°dONLNdó
    <

≥*Eyour application hasn’t called SignPrepare, would cause this failure.°dONLNd›
T
)Ø+
unsigned long°dONLNdÏ
Ã
)
_)xGetContextType(void);°dONLNd
/<
=
Õ(
XZLReturn zero if there is no current context, else the type that was specified°dONLNdO
=<
K
E*-when the application called NewSignerContext.
°dONLNd}
Q<
_¶*Signature Methods°dONLNdè
eT
qp+Size°dONLNdó
eÃ
q
 )xSignPrepare(°dONLNd•
ql
}¿(
öäconst FSSpec°dONLNd≥
q‰
}
8)x*signerFile,°dONLNd¡
}l
â‹(
¶äConstStr255Param°dONLNd“
}‰
â
)x*prompt°dONLNd⁄
âT
ïb(
≤r);°dONLNd›
õ<
©
≈(
ƒZFSignPrepare prepares the Signer Manager to sign a document or data. If°dONLNd$
©<
∑
Î*QsignerFile is not NULL, it will be used to define the signer file, while if NULL,°dONLNdv
∑<
≈
Ÿ*Lthe toolbox will prompt for the user’s signer file. Prompt is used to prompt°dONLNd√
≈<
”
Ë*Qthe user for a signer file, if "\p", the default prompt will be used. SignPrepare°dONLNd
”<
·
*)returns the size of the Signature record.°dONLNd?
Á<
ı
‚*ISignPrepare our application should  use a TRY/CATCH context to detect the°dONLNdâ
ı<ô*following errors:°dONLNdõ<¨*kSigUserCanceled°dONLNd¨    

∏(2
2The user cancelled this signer°dONLNdÀ
%
“*!request. You may choose to ignore°dONLNdÌ%
3
K*this error.°dONLNd˙;<G•(dZkSIGPasswordErr°dONLNd
9
G
Õ(b
2!The user did not enter the proper°dONLNd,G
U
”*"password for the designated signer°dONLNdOU
c
)*file.°dONLNdVk<w∫(îZkSIGSignerNotValid°dONLNdii
w
„(í
2(The signer file is not valid; perhaps it°dONLNdíw
Ö
V*has expired.°dONLNd°ùT©p(Δrvoid°dONLNd©ùé
C)xShowSigner(void);

(ÒZ:Copyright © 1993, Apple Computer Inc. All Rights Reserved.(Ò??ˇ
Æ◊#ˇˇˇˇˇ#◊

d,Palatino
.+Z.Digital Signature Demo(.

6)
.°dONLNd/<=
⁄(XZMAfter your application has successfully verified a file or object, ShowSigner°dONLNdN=<K
›*Nmay be used to display the entire distinguished name of the object’s or file’s°dONLNdùK<Y
≤*@signer. Your TRY/CATCH context should catch the following error:,
Courier°dONLNdfla<m
*kSIGOperationIncompatibleErr°dONLNd¸_
m
º(à
2ShowSigner is valid only after°dONLNd
m
{
‘*%verification; it cannot be used after°dONLNd
A{
â
√*"signing an object or file. See the°dONLNd
dâ
ó
‚*$signed object demo for an example of°dONLNd
âó
•
ø*how a button that controls this°dONLNd
©•
≥
·*%request may be enabled or disabled as°dONLNd
ϳ
¡
?*needed.°dONLNd
ŸŸTÂp(
rvoid°dONLNd
·ŸÃÂ
.)xGetSignerInfo(°dONLNd
ÒÂlÒ«(
ä
SIGSignerInfo°dONLNd‰Ò
1)x*signerInfo°dONLNdÒT˝b(
r);°dONLNd
<

≈(
,ZLAfter successfully signing or verifying an object or file, you can call this°dONLNd\
<

≈*Fmethod to copy information about the signer to your buffer. The buffer°dONLNd£
<
-fi*should be in locked memory.°dONLNd¿
3T
?Ö+Boolean°dONLNd 
3Ã
?
 )xGetCertInfo(°dONLNdÿ
?l
K«(
hä
unsigned long°dONLNdÁ
?‰
K
*)x
certIndex,°dONLNdÛ
Kl
Wπ(
täSIGCertInfo°dONLNd
K‰
W
#)x    *certInfo°dONLNd

WT
cb(
Är);°dONLNd

i<
w
Ã(
íZJGetCertInfo can be used to iterate through the certificates that make up a°dONLNdX
w<
Ö
fi*Qsignature. It returns TRUE if it finds a certificate for this index, FALSE if the°dONLNd™
Ö<
ì
Ã*Mindex is out of range, and fails on other errors. It may be called only after°dONLNd¯
ì<
°
I*4successfully signing or verifying an object or file.°dONLNd-
ßT
≥Ö+Boolean°dONLNd7
ßÃ
≥
f)xGetCertNameAttributes(°dONLNdO
≥l
ø«(
‹ä
unsigned long°dONLNd^
≥‰
ø
*)x
certIndex,°dONLNdj
øl
À«(
Ëä
unsigned long°dONLNdy
ø‰
À
M)xattributeIndex,°dONLNdä
Àl
◊
h(
Ùä$SIGNameAttributesInfo *attributeInfo°dONLNdØ
◊T
„b(r);°dONLNd≤
È<
˜
“(ZOGetCertInfo can be used to iterate through the attributes for a certificate. It°dONLNd
˜<
‡*Nreturns TRUE if successful, FALSE if the certIndex is out of range, and raises°dONLNdQ<
–*Lan error condition on other errors. It may be called only after successfully°dONLNdû<!
*'signing or verifying an object or file.,    Helvetica

°dONLNdΔ'<6ƒ*Protected Methods
°dONLNdÿ;TGp+void°dONLNd‡;ÃG
f)xInitDefaultStatusProc(°dONLNd¯GlS‹(päConstStr255Param°dONLNd    G‰S
?)x
actionString,°dONLNdSl_‹(|äConstStr255Param°dONLNd)S‰_
8)xobjectString°dONLNd6_Tkb(àr);°dONLNd9q<
È(öZTThis is called if you pass gSIGStatusProc to SignFile, VerifyFile, etc. It creates a°dONLNdé<ç
á*9SIGStatusManager object which displays the status window.°dONLNd»ìTüp+void°dONLNd–ìÃü
û)xDisposeDefaultStatusProc(void)

(ÒZ:Copyright © 1993, Apple Computer Inc. All Rights Reserved.(Ò??ˇö◊#ˇˇˇˇˇ#◊

d,Palatino
.+Z.Digital Signature Demo(.

7)
.°dONLNd/<=·(XZDispose of the status window.,    Helvetica
°dONLNdI<X≈*SIGStatusManager
°dONLNd/]<lì*Introduction
°dONLNd<q<
–*DSIGStatusManager manages the status window that is displayed when an°dONLNdÅ<ç
fi*Napplication selects the default status procedure. It is created and managed by°dONLNd–ç<õ
“*Hthe CSignature instance: your application will normally not be concerned°dONLNd
õ<©d*with it.

°dONLNd
"Ø<æz*Heritage
°dONLNd
+ΩTÀé+
Superclass°dONLNd
6Ω∫ÀÔ)f    CDirector°dONLNd
@ÀTŸç(Ùr
Subclasses°dONLNd
KÀ∫Ÿ◊)fnone

°dONLNd
Pfl<Ó¬(
    ZInstance Variables
°dONLNd
cÌT˚É+
Variable°dONLNd
lÌ∫˚’)fType°dONLNd
qÌ
8˚
x)~Description°dONLNd
}˚T
    ú(
$ritsTickCount°dONLNd
ä˚∫
    

)f
unsigned long°dONLNd
ò˚
8
    
Â)~ This is used to time the “barber°dONLNd
π
    
8

ø*pole” progress indicator.

°dONLNd
”
<
,≠(
GZStatic Variables
°dONLNd
‰
+T
9É+
Variable°dONLNd
Ì
+∫
9’)fType°dONLNd
Ú
+
8
9
x)~Description°dONLNd
˛
9T
GÎ(
brgContinueSigning Boolean°dONLNd
9
8
G
„)‰This is set TRUE when signing°dONLNd5
G
8
U
›*begins, and is set FALSE if the°dONLNdU
U
8
c
Î*!user clicks on the Cancel button.°dONLNdw
c
8
q
«*The value is passed to the°dONLNdí
q
8

Ÿ*Digital Signature Manager by°dONLNdØ

8
ç
’*the default status procedure.

°dONLNdÕ
ì<
¢z(
ΩZMethods
°dONLNd’
ß<
µ
*$Construction and destruction methods,
Courier°dONLNd˙
ªT
«p+void°dONLNd
ªÃ
«
J)xISIGStatusManager(°dONLNd
«l
”‹(
äConstStr255Param°dONLNd'
«‰
”
?)x
actionString,°dONLNd6
”l
fl‹(
¸äConstStr255Param°dONLNdG
”‰
fl
8)xobjectString°dONLNdT
flT
Îb(r);°dONLNdW
Ò<
ˇ
€(ZLCreate the status window (this uses some private classes that are defined in°dONLNd§
ˇ<

Ê*KSIGStatusManager.c). The actionString and objectString are concatenated and°dONLNd
<
fi*Kdisplayed in the window. These might typically be “Signing “ “Signed File.”
°dONLNd<!</≤*Operational methods°dONLNdP5TAp+void°dONLNdX5ÃA
)x
DoCommand(°dONLNddAlMà(jälong°dONLNdlA‰M
)xaCommand°dONLNduMTYb(vr);°dONLNdx_<m
È(àZNThe status window has a cancel button: look for it and take appropriate action°dONLNd«m<{
fl*Gby setting gContinueSigning FALSE and passing the cancel command to the°dONLNd{<â≥*manager’s superclass.°dONLNd%èTõp+void°dONLNd-èÃõ˝)xDawdle(°dONLNd6õlßà(ƒälong°dONLNd>õ‰ß
#)x    *maxSleep

(ÒZ:Copyright © 1993, Apple Computer Inc. All Rights Reserved.(Ò??ˇú◊#ˇˇˇˇˇ#◊

d,Palatino
.+Z.Digital Signature Demo(.

8)
.,
Courier°dONLNd)T5b(Rr);°dONLNd;<I
}(dZ;TCL calls this repeatedly to manage the progress indicator.,    Helvetica
°dONLNd?U<d®*
CSignedObject
°dONLNdMi<xì*Introduction
°dONLNdZ}<ã
œ*ICSignedObject lets you sign and verify the contents of an individual data°dONLNd§ã<ô
⁄*Mobject, such as a spreadsheet value or the position of an object in a drawing°dONLNdÚô<ß
‘*Kapplication. You can then store and recover the signature record as part of°dONLNd
>ß<µ
$**your application’s normal storage process.

°dONLNd
iª< z*Heritage
°dONLNd
r…T◊é+
Superclass°dONLNd
}…∫◊¯)f
CSignature°dONLNd
à◊TÂç(
r
Subclasses°dONLNd
ì◊∫Â◊)fnone

°dONLNd
òÎ<˙¬(
ZInstance Variables
°dONLNd
´˘T
É+
Variable°dONLNd
¥˘∫
’)fType°dONLNd
π˘
8

x)~Description°dONLNd
≈
T
ó(
0ritsSignature°dONLNd
“
∫

)fSIGSignaturePtr°dONLNd
‚

8

”)~The signature record, if any.°dONLNd
T
#Æ(
>ritsSignatureSize°dONLNd
∫
#—)fSize°dONLNd

8
#
È)~!The size of the signature record.

°dONLNd8
)<
8’(
SZUsing CSignedObject
°dONLNdL
=<
K
‰*OYour application should create a subclass of CSignedObject for all objects that°dONLNdú
K<
Y
*(need data-specific signature processing.

°dONLNd≈
_<
nz*Methods
°dONLNdÕ
s<
Å
–*GExcept as shown, all methods use the Failure mechanism (as described in°dONLNd
Å<
è
∞*D<Exceptions.h> to report errors. In most cases, this means that your°dONLNdZ
è<
ù
∫*Aapplication must establish a TRY/CATCH context when calling these°dONLNdú
ù<
´p*methods:°dONLNd•
≥<
ø¨*kSIGUserCanceled°dONLNd∂
±

ø
‡(
⁄
2&The user cancelled this sign or verify°dONLNd›
ø

Õ
“*!request. You may choose to ignore°dONLNdˇ
Õ

€
K*this error.°dONLNd
„<
Ô•(ZkSIGPasswordErr°dONLNd
·

Ô
∑(

2The user entered an incorrect°dONLNd:
Ô

˝
K*    password.°dONLNdE<œ(.ZkSIGSignerNotValidErr°dONLNd[

„(,
2(The signer file is not valid; perhaps it°dONLNdÑ

V*has expired.°dONLNdí'<3•(PZkSIGNoSignature°dONLNd¢%
3
‚(N
2#Programming error: your application°dONLNdΔ3
A
‡*$called Sign or Verify without having°dONLNdÎA
O
‹*$called SignPrepare or VerifyPrepare.°dONLNdW<c¡(ÄZkSIGVerifyFailedErr°dONLNd%U
c
|(~
2Verification failed.°dONLNd;k<w‰(îZkSIGInvalidCredentialErr°dONLNdTi
w
©(í
2Verification succeeded, but°dONLNdpw
Ö
›*%credentials are invalid; perhaps they°dONLNdñÖ
ì
_*
have expired.

(ÒZ:Copyright © 1993, Apple Computer Inc. All Rights Reserved.(Ò??ˇä◊#ˇˇˇˇˇ#◊

d,Palatino
.+Z.Digital Signature Demo(.

9)
.,
Courier°dONLNd1<=ó(ZZ
kSigSignerErr°dONLNd/
=
”(X
2#Some sort of error with the signer:°dONLNd2=
K
¢*the signature is not valid.
°dONLNdOQ<_
(zZ% Construction and destruction methods°dONLNdueTqp+void°dONLNd}eÃq
X)xISignedObject(void);°dONLNdíw<ÖÊ(†Z!Initialize the private variables.°dONLNd¥ãTóp+void°dONLNdºãÃó
.)xDispose(void);°dONLNdÀù<´
æ(ΔZFDelete any context and signature and dispose of the CSignature object.
°dONLNd
±<øÎ*Signing and Verifying Methods°dONLNd
0≈T—p+Size°dONLNd
8≈×
 )xSignPrepare(°dONLNd
F—l›¿(˙äconst FSSpec°dONLNd
T—‰›
8)x*signerFile,°dONLNd
b›lÈ‹(
äConstStr255Param°dONLNd
s›‰È
)x*prompt°dONLNd
{ÈTıb(
r);°dONLNd
~˚<
    
ã(
$Z=Override CSignature::SignPrepare to store the signature size.°dONLNd
º
T
p+void°dONLNd
ƒ
Ã
Ô)xSign(°dONLNd
À
l
'‹(
DäSIGStatusProcPtr°dONLNd
‹
‰
'
*)x
statusProc°dONLNd
Á
'T
3b(
Pr);°dONLNd
Í
9<
G
Î(
bZPSign completes the digital signature process. To sign an object, you should call°dONLNd;
G<
U
Ë*LSignPrepare, ProcessData, and then Sign. The statusProc, if not NULL, may be°dONLNdà
U<
c
‘*Lused to inform the user that a signature operation is occurring.  Errors are°dONLNd’
c<
q
*%reported using the Failure mechanism.°dONLNd˚
wT
Ép+void°dONLNd
wÃ
É
.)xVerifyPrepare(°dONLNd
Él
è‹(
¨äSIGStatusProcPtr°dONLNd$
ɉ
è
*)x
statusProc°dONLNd/
èT
õb(
∏r);°dONLNd2
°<
Ø
·(
 ZPBegin the process of verifying a digital signature process. To verify an object,°dONLNdÉ
Ø<
Ω
‹*Lyou should call VerifyPrepare, ProcessData, then Verify. Errors are reported°dONLNd–
Ω<
À„*using the Failure mechanism.°dONLNdÌ
—T
›p+void°dONLNdı
—Ã
›
')x
Verify(void);°dONLNd
„<
Ò
‡(ZNVerify completes the digital signature verification. Errors are reported using°dONLNdR
Ò<
ˇ¡*the Failure mechanism.°dONLNdiTp+void°dONLNdqÃ
 )xProcessData(°dONLNdl≤(:ä
const void°dONLNdã‰
#)x    *dataPtr,°dONLNdñl)à(FäSize°dONLNdû‰)
)xdataSize°dONLNdß)T5b(Rr);°dONLNd™;<I
“(dZLCompute or verify a Digital Signature. This is called for all data elements.
°dONLNd¯O<]¶*Signature Methods°dONLNd
cTop+Size°dONLNdcÃo
m)xGetSignatureSize(void);°dONLNd*u<É
±(ûZCReturn the size of the signature record, as specified—originally—by°dONLNdnÉ<ëÇ*SignPrepare.°dONLNd{óT£p+void°dONLNdÉóã
Q)xNewSignature(void);

(ÒZ:Copyright © 1993, Apple Computer Inc. All Rights Reserved.(Ò??ˇÙ◊#ˇˇˇˇˇ#◊

d,Palatino
.+Z.Digital Signature Demo(.
˚10)
.°dONLNd/<=
Å(XZ=Create a signature record using the currently-specified size.,
Courier°dONLNd>CTOp+void°dONLNdFCÃO
m)xDisposeSignature(void);°dONLNd^U<c
ƒ(~ZJDispose of the current signature buffer, if any, but do not dispose of the°dONLNd©c<qg*context.°dONLNd≤wTÉÖ+Boolean°dONLNdºwÃÉ
Q)xHasSignature(void);°dONLNd–â<ó
/(≤Z,Return TRUE if there is a current signature.°dONLNd˝ùT©p+void°dONLNd
ùé
t)xCheckForSignature(void);°dONLNd
Ø<Ω
€(ÿZLFail with an error (kSIGNoSignature) if the application hasn’t established a°dONLNd
kΩ<Àô*signature record.°dONLNd
}—T›p+void°dONLNd
֗Û
Ç)xCopySignatureToUserBuffer(°dONLNd
°›lÈà(
ävoid°dONLNd
©›‰È
)x*buffer,°dONLNd
≥Èlıà(
äSize°dONLNd
ªÈ‰ı
*)x
bufferSize°dONLNd
ΔıT

b(
r);°dONLNd
…
<

÷(
0ZNCopy the current signature to the user’s buffer. BufferSize is the size of the°dONLNd
<
#
◊*Muser’s buffer; a paramErr error condition will be raised if bufferSize cannot°dONLNdf
#<
1…*hold the entire signature.°dONLNdÅ
7T
Cp+void°dONLNdâ
7Ã
C
ê)xMakeSignatureFromUserBuffer(°dONLNdß
Cl
Oà(
lävoid°dONLNdØ
C‰
O
)x*buffer,°dONLNdπ
Ol
[à(
xäSize°dONLNd¡
O‰
[
*)x
bufferSize°dONLNdÃ
[T
gb(
Ñr);°dONLNdœ
m<
{
≤(
ñZECreate a signature record using the information in the user’s buffer.°dONLNd
{<
â
–*@CopySignatureToUserBuffer and MakeSignatureFromUserBuffer may be°dONLNdV
â<
ó
T*4used together to save and restore object signatures.°dONLNdã
ùT
©p+void°dONLNdì
ùÃ
©
.)xReadSignature(°dONLNd£
©l
µ´(
“ä    CDataFile°dONLNdØ
©‰
µ
)x*aFile°dONLNd∂
µT
¡b(
fir);°dONLNdπ
«<
’
Ÿ(
ZLRead a signature record from the indicated file. If a non-null signature was°dONLNd
’<
„
⁄*Mread, create it from the given data. The actual data includes a header record°dONLNdT
„<
Ò
ù*Ethat indicates that the data is a signature and specifies its length.°dONLNdö
˜Tp+void°dONLNd¢
˜Ã
5)xWriteSignature(°dONLNd≥l´(,ä    CDataFile°dONLNdø‰
)x*aFile°dONLNdΔTb(8r);°dONLNd…!</
⁄(JZMWrite a signature to an open file. This might be called as part of your “save°dONLNd/<=
Ÿ*Pthis object” process. aFile is a TCL data file. This also writes a header record°dONLNdh=<K
Í*Rwith the signature length: if it is called when there no signature record, it will°dONLNdªK<Y
ß*Cwrite a zero-length record that ReadSignature correctly interprets.,    Helvetica
°dONLNdˇe<t∂*CSignedDataFile
°dONLNdy<àì*Introduction
°dONLNdç<õ
æ*HCSignedDataFile lets you sign and verify the contents of an entire file.

*;:Copyright © 1993, Apple Computer Inc. All Rights Reserved.(Ò??ˇ§◊#ˇˇˇˇˇ#◊

d,Palatino
.+Z.Digital Signature Demo(.
˚11)
.,    Helvetica

°dONLNd/<>z(YZHeritage
°dONLNd    =TKé+
Superclass°dONLNd=∫K¯)f
CSignature°dONLNdKTYç(tr
Subclasses°dONLNd*K∫Y◊)fnone

°dONLNd/_<n„(âZUsing CSignedDataFile
°dONLNdEs<Å
⁄*JUse this as part of your application’s Open and Close document processing.

°dONLNdêá<ñz*Methods
°dONLNdòõ<©
–*GExcept as shown, all methods use the Failure mechanism (as described in°dONLNd‡©<∑
∫*G<Exceptions.h> to report errors. In certain cases, this means that your°dONLNd
(∑<≈
∫*Aapplication must establish a TRY/CATCH context when calling these°dONLNd
j≈<”p*methods.
°dONLNd
tŸ<Á
*$Construction and destruction methods,
Courier°dONLNd
ôÌT˘p+void°dONLNd
°ÌÃ˘
f)xISignedDataFile(void);°dONLNd
∏ˇ<

÷(
(ZInitalize the object instance.°dONLNd
◊
T
p+void°dONLNd
fl
Ã

)x    SignFile(°dONLNd
Í
l
+¿(
Häconst FSSpec°dONLNd
¯
‰
+
8)x*signerFile,°dONLNd
+l
7‹(
TäConstStr255Param°dONLNd
+‰
7
?)x
promptString,°dONLNd&
7l
C¿(
`äconst FSSpec°dONLNd4
7‰
C
*)x
*dataFile,°dONLNd@
Cl
O‹(
läSIGStatusProcPtr°dONLNdQ
C‰
O
*)x
statusProc°dONLNd\
OT
[b(
xr);°dONLNd_
a<
o
·(
äZRSign the file specified by dataFile. If signerFile is not NULL, it will be used to°dONLNd≤
o<
}
⁄*Mdefine the signer file, while if NULL, the toolbox will prompt for the user’s°dONLNd
}<
ã
—*Nsigner file. Prompt is used to prompt the user for a signer file, if "\p", the°dONLNdO
ã<
ô
”*Jdefault prompt will be used. SignPrepare returns the size of the Signature°dONLNdö
ô<
ß
›*Lrecord. StatusProc defines the user status procedure. Use gSIGStatusProc for°dONLNdÁ
ß<
µ¨*the default window.°dONLNd¸
ª<
…
¿*HBecause of the way the Think Class Library closes files, you should call°dONLNdE
…<
◊ˇ*#SignFile in the following sequence:°dONLNdi
·`
Ôf+$
1°dONLNdk
·m
Ô
Ü)
5Create a copy of the FSSpec associated with the file.°dONLNd°
˘`f("~
2°dONLNd£
˘më)
Write 
°dONLNd©
˘ë
»)$9all data and close the file. You can delete the CDataFile°dONLNd„m“(0ãobject at this time.°dONLNd¯`-f(H~
3°dONLNd˙m-
")
 SignFile using the saved FSSpec.°dONLNd7`Ef(`~
4°dONLNd7mE
)
Call DisposeSignerContext°dONLNd7K<Y
Î(tZIYou should call SignPrepare…SignFile in a TRY/CATCH context, checking for°dONLNdÅY<gÆ*the following errors:°dONLNdóo<{¨*kSIGUserCanceled°dONLNd®m
{
∏(ñ
2The user cancelled this signer°dONLNd«{
â
“*!request. You may choose to ignore°dONLNdÈâ
ó
K*this error.

(ÒZ:Copyright © 1993, Apple Computer Inc. All Rights Reserved.(Ò??ˇΔ◊#ˇˇˇˇˇ#◊

d,Palatino
.+Z.Digital Signature Demo(.
˚12)
.,
Courier°dONLNd1<=•(ZZkSIGPasswordErr°dONLNd/
=
∑(X
2The user entered an incorrect°dONLNd.=
K
K*    password.°dONLNd9S<_∫(|ZkSIGSignerNotValid°dONLNdLQ
_
ß(z
2The signer file is incorrect.°dONLNdkg<s{(êZ    wrPermErr°dONLNdue
s
À(é
2!The data file is marked read-only°dONLNdós
Å
√* (perhaps it was already signed?)°dONLNdπáTìp(∞rvoid°dONLNd¡áÃì
)xVerifyFile(°dONLNdŒìlü¿(ºäconst FSSpec°dONLNd‹ì‰ü
*)x
*dataFile,°dONLNdËül´‹(»äSIGStatusProcPtr°dONLNd˘ü‰´
*)x
statusProc°dONLNd
´T∑b(‘r);°dONLNd
Ω<À
ÿ(ÊZOVerify the signature in the file specified by dataFile.  StatusProc defines the°dONLNd
WÀ<Ÿ
ƒ*Euser status procedure. Use gSIGStatusProc for the default window. You°dONLNd
ùŸ<Á
›*Ishould call VerifyFile in a TRY/CATCH context, checking for the following°dONLNd
ÁÁ<ı`*errors:°dONLNd
Ô˝<
    ¨*kSIGUserCanceled°dONLNd˚

    
◊(
$
2$The user cancelled this verification°dONLNd%
    


“*!request. You may choose to ignore°dONLNdG


%
K*this error.°dONLNdT
-<
9¡(
VZkSIGVerifyFailedErr°dONLNdh
+

9
µ(
T
2 Verification failed: the file or°dONLNdâ
9

G
”* signature may have been changed.°dONLNd´
O<
[‰(
xZkSIGInvalidCredentialErr°dONLNdƒ
M

[
æ(
v
2Verification succeeded, but the°dONLNd‰
[

i
√*credentials are pending or have°dONLNd
i

w
œ*%expired. The context is still active.°dONLNd+
}T
âÖ(
¶rBoolean°dONLNd5
}Ã
â
')x
FileIsSigned(°dONLNdD
âl
ï¿(
≤äconst FSSpec°dONLNdR
â‰
ï
*)x
*dataFile,°dONLNd]
ïT
°b(
ær);°dONLNd`
ß<
µ
⁄(
–ZMReturn TRUE if the specified file has a signature. Note that the signature is°dONLNdÆ
µ<
Á*
not verified.

(ÒZ:Copyright © 1993, Apple Computer Inc. All Rights Reserved.(Ò??ˇ